---
title: 'Customize Theme'
description: 'Custom theme by yourself'
order: 2
---

import { Aside, Spoiler, Steps } from 'astro-pure/user'

## You Should Know

This theme is designed to "NPM Package" for the following reasons:

1. The code written in package may be frequently changed. If users change them at will, it will significantly increase the cost of subsequent updates and merging (various conflicts for code)
2. Roll back and switch between different versions easily, to maintain user stability
3. Reduce system coupling & increase reuse ability
4. The NPM Package mode can be used as a "Astro plugin" to append additional operations that enhance user experience during the build phase
5. Support some built-in commands like new, check, info, etc.
6. Use as component library for other Astro projects (yes, this project can be broken down into the UI component library): [Package details](https://www.npmjs.com/package/astro-pure).

Before you customize it, you should check [`site.config.ts`](/docs/setup/configuration#theme-configuration) to make sure there is no option that satisfy your need.

## Swizzling

This theme chose an elegant method called 'Swizzling', which is inspired by the design from [Docusaurus](https://docusaurus.io/docs/swizzling).

1. Use an IDE to quickly view the source code corresponding to a certain component (In VSCode, it is to click the component with <kbd>Ctrl</kbd>).
2. Copy to `src/components/<your prefer directory>`.
3. After modification, change the corresponding reference to your own file path.

Let's make an example to customize the `Footer` component:

<Steps>
1. Search the `Footer` in your project code:

   ```astro title="src/layout/BaseLayout.astro"
   ---
   import { Footer, Header, ThemeProvider } from 'astro-pure/components/basic'
   import type { SiteMeta } from 'astro-pure/types'
   // ...
   ---
   ```

2. Find it in theme source code:

   ```ts title="node_modules/astro-theme-pure/components/basic/index.ts"
   export { default as Footer } from './Footer.astro'
   export { default as Header } from './Header.astro'
   export { default as ThemeProvider } from './ThemeProvider.astro'
   ```

   Then you get the `Footer` component source code at `node_modules/astro-theme-pure/components/basic/Footer.astro`.

3. Copy the `Footer.astro` file to your project:

   ```bash
   cp node_modules/astro-theme-pure/components/basic/Footer.astro src/components/custom/Footer.astro
   ```

4. Solve the sub-dependencies problem:

   ```astro title="src/components/custom/Footer.astro"
   ---
   import config from 'virtual:config'

   import { Icon } from '../user' // [!code --]
   import { Icon } from 'astro-pure/user' // [!code ++]
   // ...
   ---
   ```

5. Change the reference in `BaseLayout.astro`:

   ```astro title="src/layout/BaseLayout.astro"
    ---
    import { Footer, Header, ThemeProvider } from 'astro-pure/components/basic' // [!code --]
    import { Header, ThemeProvider } from 'astro-pure/components/basic' // [!code ++]
    import { Footer } from '@/components/custom/Footer.astro' // [!code ++]
    // ...
    ---
    ```

</Steps>

Then you've done a "localization" of the component.

## Package mode

<Aside type='danger' title={'Use at Your Own Risk'.toUpperCase()}>
Keep cautious for change the underlying code <Spoiler>~~底层代码不可突破，祖宗之法不可变~~</Spoiler>, unless you know what you are doing. You should know and accept any risks & difficulties for making project complex.
</Aside>

If you want to make some breaking changes or just make a test, this method may follow "what you see is what you get".

1. Making sure you have the original theme code (`./packages/pure`). If yo've deleted it, download it from the [Releases](https://github.com/cworld1/astro-theme-pure/releases).
2. Link it to your project using your package manager.
3. Then change the theme code as it is a part of your code!

<Aside type='tip'>
For bun user, please refer to [Deployment#Package Mode](/docs/setup/deployment#package-mode)

This can also help you correctly build your project on cloud CI/CD.
</Aside>
